home *** CD-ROM | disk | FTP | other *** search
/ C/C++ Interactive Reference Guide / C-C++ Interactive Reference Guide.iso / c_ref / csource3 / 157_01 / qe123.doc < prev    next >
Encoding:
Text File  |  1987-10-12  |  12.6 KB  |  266 lines
  1. DOCUMENTATION FOR EDITOR QE AND QED Version 1.23
  2.  
  3. DATE:     29 APRIL 1986
  4. VERSION:  1.23
  5. AUTHORS:  Nigel Gilbert and James Haefner
  6.  
  7.     This report documents changes made in the screen editor 
  8. QE for BDS C (tm) (version 1.50a) and QED for DeSmet C (tm) 
  9. (version 2.41).  I assume the reader is familiar with 
  10. previous documentation for the editor 'e' and the 
  11. documentation file QE/D.DOC for version 1.0 of the QE and 
  12. QED editors.
  13.  
  14. CHANGES COMMON TO QE AND QED
  15.  
  16.     The following changes apply to both the CP/M and MSDOS 
  17. versions.
  18.  
  19.     1.    WORD WRAP.  Automatic word wrapping has been added.  When 
  20. text input reaches a prescribed column, the editor will break 
  21. the current line between words, insert a carriage return at the 
  22. end, and continue to permit input on the next line.  The column 
  23. for wrapping is set in the editing context screen (^QKR).  In 
  24. addition, there are two methods for reformatting existing text 
  25. to fit within a specified column setting.  First, a "quick" 
  26. single paragraph reform function has been added to reformat a 
  27. paragraph from the current line on which the cursor lies to the 
  28. end of the paragraph.  Since "hard" (sensu WordStar) carriage 
  29. returns are appended to each line, the end of a paragraph is 
  30. the line above (a) a blank line (no text), (b) a line that 
  31. begins with white space, or (c) the end of the file.  The 
  32. commands for this method are ^QP (for "prettify paragraph"). 
  33.  
  34.     The second method to reform text is via the "block" commands, 
  35. where an option has been added to permit a defined block to be 
  36. reformed to fit within a specified right margin.  The
  37. commands for this method are: ^KBR, followed by the definition 
  38. of the text block.  The second method will not reform across 
  39. paragraghs (i.e., concatenate text of several paragraphs), if 
  40. the paragraphs are defined by separating empty lines of text.  
  41. "Paragraphs" separated only by leading white space on the first 
  42. line of succeeding paragraphs will be converted into a single 
  43. paragraph. 
  44.  
  45.     Reformatting may be turned off in two ways.  First, the 
  46. header file, QE.H, contains a "#define WWRAP (YES)" 
  47. statement that will permit or prohibit compilation of the 
  48. relevant code.  Second, the editing context screen (via 
  49. ^QK) permits setting of the right margin.  If the right 
  50. margin is 255 (current value of the maximum line length), 
  51. reforming is effectively turned off, as any attempts to 
  52. input text beyond this column results in a truncated line, 
  53. as in the original 'e'.
  54.  
  55.     New functions for word wrapping have been added to QE2 
  56. and QE6, with minor additions to QE1, QE, and QE4.  QE6 
  57. contains "reform()" which does most of the work; QE2 
  58. contains "char *firstwhite()", which returns the address of 
  59. the first non-white character from the right-hand end of 
  60. the current line.  The latter function is used both during 
  61. block reforming and reforming that occurs when inserting 
  62. text.
  63.  
  64.     2.    VERSION DOCUMENTATION.  Unadulterated CP/M, as we 
  65. all know, does not record the date and time of file 
  66. formation or alteration.  I have added code that minimizes 
  67. the effort required to update a commented line at the 
  68. beginning of the file indicating the version number, 
  69. current date, and current time.  If no version 
  70. documentation line exists, one is added.  If this is the 
  71. case, the user is prompted for the set of comment 
  72. delimiters in which to enclose the line.  Thus, for a file 
  73. to be used as input to the ROFF4 formatter we have this 
  74. line at the top of the file:
  75.  
  76. ..  VERSION 0003  (DATE: 13/10/86)  (TIME: 22:09)  ..
  77.  
  78.     The code has been structured such that, if a clock on 
  79. CP/M systems is available, the user can insert code to 
  80. determine the date and time with no user input.  Most MSDOS 
  81. systems seem to have clocks (even if they have no battery 
  82. backup), so for those systems, date and time are determined 
  83. via DOS calls and no user input is required.  The version 
  84. number is incremented automatically.
  85.  
  86.     CP/M users with no clock (like myself) must provide the 
  87. necessary information, which is a pain, but I have 
  88. attempted to make it as easy as possible.  The date and 
  89. time are stored as five bytes in the CP/M zero page at 
  90. location NOWLOC, which is currently set to 50 hex.  In both 
  91. of my systems, this location is not overwritten by normal 
  92. program execution.  In fact, one of the BIOSes does not 
  93. even zero these locations on a physical reset.  In any 
  94. case, the appropriate values may need to be set for 
  95. different systems, but if 5 contiguous safe locations exist 
  96. anywhere in memory (including high memory, above BDOS), 
  97. then the date and time should persist through exit and 
  98. re-entry to the editor.
  99.  
  100.     No user input is required in QED on MSDOS systems, once the 
  101. initial version comment line has been inserted.  On CP/M 
  102. systems without clocks, only the current date and time strings 
  103. must be edited on the status line during a file save operation.  
  104. Depending on the time period since the last power down or 
  105. system reset and the last alteration of the file, this can 
  106. involve as little as changing the single character on the 
  107. status line that is the last digit of minutes.  If you wish to 
  108. update only the version number and leave the date and time as 
  109. they are, then pressing <CR> twice (for date and for time) will 
  110. leave these unchanged.  In general, typing a carriage return 
  111. will leave the requested information (i.e., the date or time) 
  112. unchanged.  The editing possibilities for the entry are 
  113. identical to string searching; in particular, backspacing, 
  114. altering a character, then typing ^L will alter the character 
  115. and replay the remainder of the entry.  
  116.  
  117.     Inclusion of this code is controlled by "#define VRSNNUM 
  118. (YES)" and "#define VRSNDATE (YES)" statements.  Thus, 
  119. users not wishing this feature may exclude it.  (Check 
  120. these settings in QE.H before compiling.)  In addition, 
  121. version update on a file may be frustrated within the 
  122. editor via the editing context screen (^QKV).  If you 
  123. forget to turn off version updating globally via ^QK, you 
  124. can still prevent version updating by typing '~' at the 
  125. prompt for a left comment symbol (no previous version 
  126. comment line) or at the prompt for the current date.
  127.  
  128.     This facility seems to be relatively useful, especially in 
  129. CP/M, but the user should be prepared to suffer some 
  130. embarrassment upon showing to friends listings of difficult 
  131. programs that have endured many editing-compile cycles and, 
  132. thus, have large version numbers.  You will see some of these in 
  133. the source code of QE.
  134.  
  135.     All of the code for version documentation is in the new 
  136. files QE11 and QED11.
  137.  
  138.     3.  RV UTILITY.  I also include a short utility to report the 
  139. version number for a set of CP/M files.  The command line 
  140. syntax is: 
  141.  
  142.     rv [-cd] ambigfilename
  143.  
  144. where -c means compare the version numbers of the files on 
  145. the current drive with those of the same names on drive 
  146. 'd'.  "Ambigfilename" is a set of ambiguous filenames 
  147. according to the convention of "wildexp()", which is 
  148. required.  E.g., to list on the console the version 
  149. comments of all the QE text files and compare with those on 
  150. drive B, do this:
  151.  
  152.     A>rv -cb QE*.* !QE*.CRL !QE*.COM
  153.  
  154.     This utility has obvious applications to maintaining 
  155. backups of current versions.  Remembering which CRL and COM 
  156. files to backup is the responsibility of your own personal RAM.
  157.  
  158.     4.    EXPERT MODE.  The verbose prompts for various command 
  159. options (e.g., block movement) can be replaced with a terse 
  160. list of letter options on the statusline that does not 
  161. overwrite the displayed text.  This is the current default 
  162. condition when the editor is loaded (change this default in 
  163. QED.C).  It can be toggled on and off on the command line (-E), 
  164. or in the "editing context screen" (^QKE). 
  165.  
  166.     5.    SCROLLING.  Speed of scrolling has been increased.
  167.  
  168.     6.  LINE UNDELETE.  A line deleted via ^\ or a partial 
  169. lined deleted from the current cursor to the end of the 
  170. line using ^QY is stored in a buffer.  This buffer can be 
  171. inserted below any other line using ^^.  This permits 
  172. an easier method of moving single lines without defining a 
  173. "move" block; it is also a more flexible "undo" mechanism.  
  174. I thank Professor Solve Hulberg of Stockholm for suggesting 
  175. this improvement.
  176.  
  177.     7.    DISPLAY OPTIONS.  (a) Since ^^ is now used for 
  178. inserting a deleted line, onscreen help is displayed with a 
  179. slightly more verbose command sequence.  The toggle ^QO (for 
  180. "onscreen") will do it during text insertion.  Help can 
  181. also be turned on from the "editing context screen".  (b) 
  182. Cursor movement speed and text display speed can be 
  183. increased by turning off the display of the current line 
  184. and column on the status line using ^QL or in the 
  185. "editing context screen". 
  186.  
  187.     8.  BUG FIXES.  
  188.         (a)  Delete to end of line (^QY) did not erase the screen 
  189.              properly when the screen had been scrolled horizontally 
  190.              for long lines.  
  191.         (b)  Under certain circumstances, the current edited line was 
  192.              lost after a "save" and a "return" command.  
  193.  
  194.  
  195. CHANGES SPECIFIC TO QED (MSDOS VERSION):
  196.  
  197.     1.  QUICK BACKUP.  ^QB copies the file currently being edited to 
  198. a specified default directory.  This directory is set in the editing 
  199. context screen (via ^QK); the current default directory is: B:\.  
  200. This feature is valuable for those using RAMDISKS to make frequent 
  201. hard backups of the file.
  202.  
  203.     2.  IBM-PC VIDEO DRIVER. QEDIBMPC.C contains the code to 
  204. permit QED to run on an IBM-PC without using a terminal driver 
  205. such as ANSI.SYS.  This code uses software interrupts 10 hex, 
  206. but does not write directly to the video memory.  Consequently, 
  207. this PC version of QED does not rewrite the screen as quickly 
  208. as Tearle's GED, but has the advantage that it will not 
  209. interfere with other programs also attempting to control the 
  210. screen (e.g., certain multitasking PCDOS enhancements, 
  211. multiuser operating systems like XENIX, or the much hoped-for ADOS 
  212. for the 80386).  Avoiding direct use of the video memory should 
  213. also permit porting QED to other MSDOS machines using 
  214. non-IBM-compatible memory-mapped video (e.g., DEC Rainbow, 
  215. HP150, future IBM PCs ???, etc.).  Linking will also 
  216. require the file QEDPCIO.O which is a short version of IBM-PC 
  217. video drivers supplied by C-Ware.
  218.  
  219.     3.  SPLITTING FILES.  A major limitation of 'e' and all of 
  220. its derivatives of which I am aware is that the structure of 
  221. locations of line numbers must remain in memory and is not 
  222. swapped to disk as is the actual text located at each of the 
  223. line numbers.  As a consequence, file length is limited by the 
  224. amount of memory available to store the line number addresses.  
  225. In my MSDOS system using DeSmet C (64K data area only) there is 
  226. space for approximately 11750 lines.  For most programming (the 
  227. original purpose of 'e'), this is not a serious problem, but 
  228. occasionally data files or large assembly langauage programs 
  229. will exceed this limit.  
  230.  
  231.     In Version 1.23 of QED, when this line limit is 
  232. approached, the user is queried to determine if he or she wishes 
  233. to split the file at its current line.  If yes, the user is 
  234. prompted for a filename, the lines are written to the file, 
  235. then deleted from the current file being edited, and the new 
  236. "first" page of the second segment of the original file is 
  237. displayed.  Either "pip" or "copy" will concatenate the pieces 
  238. back together, if desired.  With this code, I have successfully 
  239. edited a contrived 360K file of about 15000 lines of 8086 
  240. assembly language code. 
  241.  
  242.     4.  INVISIBLE STRING REPLACEMENT.  The default mode of 
  243. unqueried string replacement (^QA...W, where dots are the 
  244. strings) is NOT to show the changes as they are being made.  
  245. This increases the speed of replacements considerably.  You can 
  246. revert to the old way using the V (verbose) option: ^QA...WV).  
  247. Of course, if you request to be queried, each occurrence of the 
  248. search string is displayed. 
  249.  
  250.     5.  NO RV.C.  Although QED version 1.23 automatically updates 
  251. the version number and date and time when a file is saved, I 
  252. have not provided an MSDOS version of RV (the Report Version), 
  253. as I did for QE (CP/M). 
  254.  
  255.     6.  SHORT DOCUMENTATION.  For those not wishing to glean the 
  256. operation of qed from e.doc, qe/d.doc, and this documentation, I 
  257. have included a short description of how to use QED version 1.23 
  258. on the file QEDPC.DOC.  The name refers to the PC version, but 
  259. it is relevant for other versions of QED as well.
  260.  
  261.     7.  CONTROL Z.  Files are not assumed to terminate with a 
  262. control-Z (0x1a) as the last bytes, as required by CP/M and 
  263. MSDOS version 1.x.  Control-Z is not written to files saved by 
  264. QED ver. 1.23.  This change is in response to apparent 
  265. problems with "include" files having ^Z in MASM.
  266.